home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / sound / moddis00.zip / readme < prev    next >
Text File  |  1994-03-19  |  14KB  |  355 lines
  1. Mod Disassembler v 0.00
  2.  
  3. Introduction:
  4.  
  5. This program is used to dis-assemble a .mod file.  It creates a human
  6. readable file describing everything in the .mod file.
  7.  
  8. It can optionally dump the samples in separate files in .wav or raw
  9. format.  The wav and raw formats can be used by other sound editing
  10. programs, and can easily be converted into other formats by conversion
  11. utilities such as sox.
  12.  
  13. The dis-assembled mod file can be viewed or edited.  A companion program
  14. modcomp can re-assemble the mod file.  (modcomp is not yet available as of
  15. the date of this writing).  Mod_dis and modcomp can be used to compose
  16. or modify mod files using any standard text editor, and can be used on
  17. any machine, even those that cant play the files.
  18.  
  19. Mod_dis has been successfully compiled and tested on
  20.     * unix - IRIX (SGI), SunOs 4.1.1 (Sun)
  21.     * msdos
  22.  
  23. The source code is provided.  Other ports are encouraged.  Send me some
  24. e-mail if you successfully port to a machine mot listed above.
  25.  
  26. The msdos executable is included for immediate use by those without
  27. compilers.
  28.  
  29. The program is freely distributible provided the copyright notices
  30. remain intact.
  31.  
  32. Usage: mod_dis [options] file.mod >file.dis
  33.  options:
  34.   -c n = set number of channels (aka voices, tracks) to n
  35.   -i n = set number of instruments (aka samples) to n
  36.       without -c and -i, mod_dis will attempt to figure out
  37.       the file format
  38.     Note: you normally do not need to set a -c or -i, however in
  39.           rare circumstances where a mod file is known to be good,
  40.           however has an unknown tag, you can try setting -c and -i
  41.           to dis-assemble.
  42.  
  43.   -np = do not disassemble patterns
  44.   -ns = do not disassemble samples
  45.     Note: by default patterns and samples are dis-assembled.  However,
  46.            if you want to just see some header information, you can
  47.           specify -np -ns to give you a more compact file.
  48.  
  49.   -u  = unused patterns
  50.       sometimes there are more patterns in the file than are actually used
  51.       in the song.  By default these are ignored.  With the -u flag they are
  52.       disassembled.
  53.  
  54.     Note: If you specify -np, you will not get any patterns dis-assembled.
  55.  
  56.   -v = verbose (another -v = more verbose)
  57.  
  58.     Note: Normally only errors are reported to the error output (your
  59.           terminal).  -v will also report some internal program
  60.           diagnostics as well as warnings.  -v -v will give you even
  61.           more.
  62.  
  63.     Note:    Additional comments may be placed in the disassembled
  64.         output when you use -v.
  65.  
  66.   -f x = format of samples, values of x are:
  67.          i=internal, s=raw samples (.sam),
  68.          a=ascii (.txt), w=Microsoft wave (.wav)
  69.          w1=.wav at 11025 Hz
  70.  
  71.     Note:    -ns will override the -f flag.
  72.     Note:    -f i is the default, causing sample values to be
  73.         dumped in a textual format at the end of the
  74.         dis-assembled output.  You can redirect the
  75.         sample dump to another file by specifying one
  76.         of the other -f switches.
  77.     Note:    The name of the external file can be controlled
  78.         with the -p switch.
  79.     Note:    If there are more than one instrument in the source
  80.         file (very likely), you will get multiple sample
  81.         files.
  82.     Note:    The .sam format is simply a stream of unsigned 8-bit
  83.         values.
  84.     Note:    The .wav file is encoded to play back at 16574 samples/sec.,
  85.         which corresponds to the standard C-3 playback rate.  If your
  86.         sound card or wav editor doesnt like this rate, you can
  87.         use the -f w1 flag to create a .wav file which will
  88.         play back at the standard 11025 Hz, the tone of the
  89.         resultant sample will be lowered somewhat when played
  90.         back, mod_dis does not adjust do any re-sampling to
  91.         compensate.
  92.     Note:    Some features of the instruments are not placed in
  93.         the sample files, like finetune, repeats, volume, etc...
  94.         Hence playback software is not likely to reproduce
  95.         the same sound as the sample when played as part of the
  96.         .mod file.
  97.         However the standard .wav file will include an INFO block
  98.         which will encode these values into the "comment" field.
  99.         The modcomp software will make use of this specially
  100.         formatted comment.
  101.     Note:    It is not likely any of the other major sound file
  102.         formats will be supported.  Thre are many tools which
  103.         can convert to/from these formats.  However,
  104.         I will make an effort to support any standard format which
  105.         allows you to specify finetune, names, and loop points
  106.         so that all of the sample information can be encoded.
  107.  
  108.   -p prefix = prefix of sample output files (defaults to inst)
  109.   -s suffix = suffix of sample output files (override format default)
  110.  
  111.     Note:    Use the forward slash (/) to separate directories instead
  112.         of the backward slash, even in MSDOS.
  113.     Note:    -p and -s are only useful when the format is not
  114.         internal.
  115.     Note:    The name of the files created will be
  116.             <prefix>nn<suffix>
  117.         where nn is the sample # (0 thru 31 in most .mod files).
  118.     Note:     When specifying a prefix, you can give a leading
  119.         directory path.  Use the forward slash (/) to separate
  120.         directories instead of the backward slash, even in MSDOS.
  121.     Note:    Make sure you leave enough room to hold the extra 2 digits
  122.         generated.  Some filesystems (namely MSDOS) have filename
  123.         length limits.
  124.     Note:    The suffix defaults as follows:
  125.             -f w or -f w1    .wav
  126.             -f s        .sam
  127.             -f a        .txt
  128.  
  129.  file.mod = input file
  130.  
  131.     Note:    MED, S3M, STM, and other formats are not supported at
  132.         this time.  This is mainly due to the lack of useable
  133.         documentation on the file formats.  If you have some
  134.         docs, you are welcomed to send them to me.
  135.  
  136.  file.dis = output file
  137.  
  138.     Note:    The output normally goes to the terminal unless you redirect
  139.         it.
  140.     Note:    Some mod files can generate dis-assemblies over 4 Mb. in
  141.         size.  Use the -np and -ns, or -f options to limit the
  142.         material written to the dis-assembly.
  143.     Note:    Some text editors may fail to load very large dis-assemblies.
  144.         Get a better editor.
  145.  
  146. Examples:
  147.  
  148.     mod_dis -v -f w -p abc abc.mod > abc.dis
  149.  
  150.     - dis-assemble abc.mod to abc.dis, samples will be written
  151.       to abc0.wav, abc1.wav, etc...
  152.     
  153.     mod_dis -np -ns abc.mod > abc.dis
  154.  
  155.     - dis-assemble only the header information of abc.mod
  156.  
  157. Diagnostics:
  158.  
  159.     Generally speaking, if you get error messages, its likely that
  160.     the .mod file is not in the standard mod format.  If you dont
  161.     understand the error message, look at the documentation for
  162.     mod file formats and the source code.
  163.  
  164.     mod_dis is fairly pessimistic when it finds something that is
  165.     not standard.  Use the "-v -v" flag to see all the warnings.
  166.     Due to the wide variety of Mod trackers in use, there are
  167.     many interpretations of the mod format specification in popular
  168.     programs.
  169.  
  170.     If you are absolutely sure your mod file is standard and contains
  171.     no errors, send me some e-mail and I'll check it out.  It could
  172.     well be that the program has bugs.
  173.  
  174. Disassembled mod output:
  175.  
  176.     The output is created in such a way as so it can be fed as input
  177.     to the companion program "modcomp" to re-compile it into a .mod
  178.     file.  The language specification is still evolving so whem
  179.     modcomp is released, it is likely that an updated mod_dis will
  180.     be released.  The output format may be changed slightly.
  181.  
  182.     The sample info (length, repeat offset, repeat length) is printed
  183.     out in bytes.  This is the most portable.  The dummy amiga
  184.     word is not included, only the real sample information.
  185.     This avoids any confusion about whether to add or subtract, and
  186.     converting from words to bytes.  Let modcomp do the work for you.
  187.  
  188.     It is common practice to have sample names which have nothing to 
  189.     do with the sample itself, sometimes even have a sample name
  190.     for a sample with no data.  These are included in the disassembly.
  191.  
  192.     Sometimes non-ascii characters are used in sample names, presumably
  193.     they display as interesting graphical characters on some machines.
  194.     Those characters may or may not be put in the disassembly
  195.     correctly, and may or may not display right in your text editor.
  196.     It is an unportable use and is discouraged.  Future implementations
  197.     may strip unportable characters.
  198.  
  199.     C++ style comments are sometimes placed in the output.  Mod